Here are examples (the language here is VB but the standards apply to
all languages):
Correct Structure
Notice that each block of code
is indented. Always indent each level of logic - each block. Blocks are
bounded by control structures such as: if..then..elseif...endif, loops of
all kinds, subs and functions, select case, etc. if averagecost > 45 then
customercost = customercost + bonus
else
customercost = customercost + (bonus * 0.75)
end if
Correct - Even Better With Comments Added
Comments
always are inline with the code they describe. Generally the
beginning of a big section has a blocked in comment. ' **************************************
' * calculate the cost to the customer *
' **************************************
if averagecost > 45 then
customercost = customercost + bonus
else
customercost = customercost + (bonus * 0.75)
end if
' *********************************************************
' * perform a loop 77 times and provide continuing status *
' *********************************************************
for counter= 1 to 77
response.write "The counter = " + cstr(counter)
next
' ********************************************************************************
' * a subroutine that replaces response.write message with: saysomething message *
' ********************************************************************************
sub saysomething (message)
' notice how response.write is called here
response.write message
end sub
Comprehensive Example - Correct Structure and Comments
Notice that each block of code is indented. Comments always are
inline with the code they describe. Generally the beginning of a big
section has a blocked in comment and the lower less significant levels
comments are not blocked. Always indent each level of logic - each block.
Blocks are bounded by control structures such as: if..then..elseif...endif,
loops of all kinds, subs and functions, select case, etc. ' *****************************************************************
' * determine if a customer should be informed of a special offer *
' *****************************************************************
if customerbalance > 1000 then
' customer owes at least $1000 so an offer is possible:
if date() < cdate(offerexpires) then
' offer still active so tell customer - and count down from 10 to 1:
saysomething "We have a deal for you! The deal count down is at "
for i = 10 to 1 step -1
saysomething cstr(i) + "..."
next
saysomething "!"
else
' offer has expired:
saysomething "Too late! Sorry."
end if
end if
Incorrect - Poor Code Structure
No indentation. Code
is hard to read. Comments are missing. if ac > 45 then
cc = cc + bonus
else
cc = cc + (bonus * 0.75)
end if
for a= 1 to 77
response.write "The counter = " + cstr(a)
next
sub saysomething (m)
response.write m
end sub
if cb > 1000 then
if date() < cdate(offerexpires) then
saysomething "We have a deal for you..."
else
saysomething "Too late! Sorry."
end if
end if
Incorrect - Comments Hard to Read
Comments
must be in line with the code they describe and you must have
adequate white space around the comments and between the comments and the
code. Comments are to appear before the code they explain - never
after!
Comment is indented too far: ' **************************************
' * calculate the cost to the customer *
' **************************************
if averagecost > 45 then
customercost = customercost + bonus
else
customercost = customercost + (bonus * 0.75)
end ifNo space between comment and code it describes:
' calculate the cost to the customer
if averagecost > 45 then
customercost = customercost + bonus
else
customercost = customercost + (bonus * 0.75)
end if
Comment after code it describes: set cn = Server.CreateObject("ADODB.Connection")
cn.open "Provider=sqloledb;Database=test;UID=sa;PWD=;"
' just finished connecting with the database